home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #1 / Amiga Plus CD - 2000 - No. 1.iso / Tools / Text / Edit / GoldED-Demo / installdata / golded / developer / syntax / readme
Encoding:
Text File  |  1999-12-03  |  5.0 KB  |  100 lines
  1. CONTENTS
  2.  
  3.   Syntax parser example code.
  4.  
  5. COPYIGHT
  6.  
  7.   ©1999 Dietmar Eilert. All Rights Reserved.
  8.  
  9.   Dietmar Eilert
  10.   Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  11.   Phone: +49-(0)179-5987061 German/English
  12.   E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  13.   E-Mail: dietmar_eilert@yahoo.de (alternative address)
  14.   WWW:    http://members.tripod.com/golded
  15.   Mirror: http://members.xoom.com/golded
  16.  
  17. ABOUT
  18.  
  19.   The  source  drawer  containes  three  fully  compilable  shared  libraries
  20.   implemented  for  DICE  demonstrating  how  one  can  write a syntax parser
  21.   library  (library  code  &  description  based  on  Matt  Dillon's  example
  22.   library):  Some knowledge in shared libraries is required to understand the
  23.   code. The basic thing to remember is (1) that a shared  library  is  NOT  a
  24.   normal  C  program,  and  (2)  the  interface calls MUST be reentrant, i.e.
  25.   multiple tasks can make a library call simultaniously.
  26.  
  27. BASICS
  28.  
  29.   Syntax parsers are libraries, loaded by the editor at run time. They  parse
  30.   the  lines  of  a text and return syntax descriptions to the editor. Syntax
  31.   parsers do not contain  rendering  code:  The  editor  is  responsible  for
  32.   rendering  to  the  display (and for briefing the syntax parser if the user
  33.   modifies the text). Syntax parsers have to implement a fixed set of library
  34.   functions   used   by   the   editor.  These  functions  are  described  in
  35.   "autodoc/scanlib.doc". The most important function is  ParseLine():  it  is
  36.   called  by  the  editor  to  obtain syntax desciptions while refreshing the
  37.   display: The editor will pass a text line to the parser, the parser returns
  38.   a  syntax  description.  This basic mechanism is supplemented by additional
  39.   library calls to support high performance syntax  parsing  (simple  parsers
  40.   may  choose  to  ignore  most  of  them). Two classes of syntax parsers are
  41.   supported:
  42.  
  43.   1. Context parser
  44.  
  45.   Context parsers understand complex syntax elements consisting  of  multiple
  46.   lines  (e.g. a C parser recognizing comments). Context parsers are the most
  47.   complex parsers because they have to process every action performed by  the
  48.   editor:  deleting  the first line of a file might influence highlighting of
  49.   the last line. The editor will keep  the  parser  up-to-date  by  "sending"
  50.   notifies  (ie.  calling  a parser function). A context parsers should use a
  51.   syntax chache in order to speed up parsing: results of prior parser  passes
  52.   should  be cached for each line. Context parsers tend to be slow. A context
  53.   parser example is available as example_context.
  54.  
  55.   2. Non-context parser
  56.  
  57.   Non-context parsers examine single lines only. They are unable to recognize
  58.   syntax  elements  consisting  of  multiple  lines.  Non-context parsers are
  59.   considerably less complex than context parsers. Some of  them  will  use  a
  60.   syntax  cache  (consuming  memory), some of them are fast enough to provide
  61.   real-time parsing. Two examples found in the source drawer are  non-context
  62.   parsers  highlighting  C++  comments (C++ comments are introduced by a "//"
  63.   and terminated by the end of the line): the first example  "example_cached"
  64.   uses a cache, the second example "example_simple" doesn't use a cache.
  65.  
  66.   Generic syntax parsers
  67.  
  68.   Syntax scanners made for a specific language  (for  example  a  C++  syntax
  69.   parsers)  usually have built-in rules and a built-in dictionary for finding
  70.   keywords. However, the editor also  supports  generic  configurable  syntax
  71.   scanners  not  made  for  a  specific  language  by  providing  a  standard
  72.   configuration dialog. In this dialog, the user  can  specify  keywords  and
  73.   other  language  elements.  These  configuration  details are passed to the
  74.   syntax parser when it is started. Parser specify the configurable  elements
  75.   in their properties flag field. This information is evaluated by the editor
  76.   to present the user with the correct configuration dialog. Parsers may also
  77.   provide  their  own  setup  dialog  overriding  the  built-in configuration
  78.   dialog.
  79.  
  80. FILES
  81.  
  82.   source/example:
  83.  
  84.   DEFS.H      parser independant header stuff   (do not change)
  85.   LIB.C       parser independant basic code     (do not change)
  86.   INIT.C      parser independant initialization (do not change)
  87.   TAG.A       parser dependant code
  88.   FUNCS.C     parser dependant code
  89.  
  90.   DEFS.H, LIB.C and INIT.C are parser  independant  modules.  Do  not  change
  91.   these  files.  FUNCS.C is the parser code decribed by scanlib.doc. TAG.A is
  92.   the startup code with only one modifications required  if  used  for  other
  93.   projects: the name of the library. "TAG.A contains a subset of the standard
  94.   startup code LIB/AMIGA/C.A and assumes non-resident compilation  (i.e.  you
  95.   cannot use the -r option). This isn't a problem since the -r option doesn't
  96.   gain you anything as far as shared libraries  go.  The  individual  library
  97.   interface  routines are declared with the LibCall macro, defined in DEFS.H,
  98.   which ensures the small-data pointer is set  up  for  all  interface  calls
  99.   allowing use of the small-data model" (Matt Dillon).
  100.